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Getting started 


To keep these instructions simple to use, I'm focusing on the assembly rather than an in-depth explanation. 


If you have specific questions on “why” rather than “how”, please post on our forum at 
https:/www.petoi.com/forum or write to info@petoi.com. 
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11 x High torque digital metal servos 


= Suspended and tunable center of mass 
Programmable gaits and behaviors 4 


* Patent Pending 


You can support us by shopping at www.petoi.com/store. Our social media 
(Instagram/Twitter/Facebook/GitHub) account is @PetoiCamp. Share your build with us by tagging #nybble 
#petoi fopencat so that we can repost for you! 


(@) Last Updated: 01/03/2022 


1 0s Tools and Preparation 


"A beard well lathered is half shaved.” [] 


1.1. Preparation 


Prepare a clean desk and some small boxes to unzip the package. Take a picture of the kit contents in case 
you lost something later. 


©) I's better to work in a room without carpet or textured mosaic. Little screws and springs can 
magically hide themselves if dropped onto the ground. 


1.2. Tools and accessories 


Required 
Tool Notes 
Utility knife Cut the tabs holding the wooden puzzle pi 
Sanding paper/foam Remove pointy fibers 
Flat and Phillips screwdrivers For M2 (diameter = 2mm) screws 
Computer with Arduino IDE Install the latest Arduino IDE 
USB to mini USB cable Connect the uploader to computer. Not mic 


Don’t mix with regular AA batteries (1.5V)! 


2 x 14500 3.7V Li-ion batteries 8 
The capacity should be around 800mAh. 


Smart charger for batteries Wrong charger may cause danger! 
Optional 
Tool Note 


Soldering iron w/ accessories Solder the decorative LED to ultrasound se 


HC-05 bluetooth module Wirelessly upload sketch and communicat 


Color paints Give your Nybble a unique look 

3D printer w/ accessories Add your special design 
Arduino/Raspberry Pi kit Add more gadgets to Nybble 

Multimeter Test and debug 

Oscilloscope Test and debug 

Hot glue/super glue Avoid using them. OpenCat is designed to 


2 U Open the Box 


“life is like a box of Nybble.” 0 


The actual kit contents and packaging method may be adjusted as we improve the product. This instruction 
will keep consistent with the current namespace. 


Newest kit contents: 
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Early kit contents: 


2.1. Cut body pieces off the baseboard. 


There might be some tar residue on the wooden pieces from laser cutting. Use a piece of wet soft tissue to 
clean up the board. 


The functional pieces are attached to the baseboard by lightly cut tabs. Though you could pop those pieces 
out by hand, it's very highly recommended that you use a knife to cut on the backside of the tabs to avoid 
potential damage to the middle layer, where the fiber direction is perpendicular to the surface fiber. 


After taking out all the pieces from the baseboard, you are encouraged to bend and break the remaining 
structures on the baseboard, to understand the mechanical properties of plywood, such as anisotropic 
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2.2. Remove pointy fibers. 


Use the sanding foam to clean up any thorn on the pieces. Don't sand too much or it may affect the tightness 
between joints. 


2.3. Screws 
There are five different screws used in the kit. 'm coloring them differently to better indicate their locations. 


Not all screws are required to assemble Nybble. Not all holes on the puzzle pieces need screws. Observe 
the assembling animation carefully to locate them. 


all 


e Ais for attaching servo arms. D (sharp tip) is for attaching servos to the frame. A and D come in each 
servo's accessory pouch with plastic servo arms. 


e Bis for attaching servo arms/circuit boards to the frame. 


®) In later versions, it may be replaced by C to simplify the kit content. In that case, if the hole is too 
small for screw C's flat tip, use screw D to pre-tap. 


e C (flat tip) is for binding the thighs. 


e _E (always the longest) is for attaching the battery holder. 
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2.4. Springs 
There are three different springs: F, G, H. 
e The big spring F is used for elastic connection in the thigh. There's one spare unit. 


e The hard short spring G is for the neck 
| 5 It's replaced by spring F in later versions 


e The soft short spring H is for attaching the battery holder. 


2.5. Servos 


We are switching to a new servo manufacturer from recent batches. Previously, MG92B was used for the 
four shoulder joints. MG90D was used for other joints. 


The new servos are differentiated by their cable length. Shorter cables are used for the neck, tail, and four 
shoulder joints. Longer cables are used for head tilting and the four knee joints. 


MG90D Shorter Cable Longer Cable 


Joint Indexes of Nybble 


@, For hobbyist servos, there are several fields where they can differentiate. 


In the Nybble kit, we are using ODMed metal gear, digital PWM, HV servos with bearing, and 
brushed iron core motors. Other generic servos can still work with the OpenCat framework but may 
need more trials and errors for best performance. 


Gear Signal Protocol Voltage Motor Bearing 
Plastic Analog PWM BV Brushed None 
Metal Digital Serial HV (up to 8V) Coreless Yes 
Brushless 


3 Ù Assemble the Frame 


“The whole is more than the sum of its parts” Il 


3.1. Head and neck 


3.1.1. Part list 


Part List 


mid 

ear 

mouth 

eye 

chin 

mg90d 

screw D X 
base 

neck X 
lock X 
servo arm | 
servo arm J 
screw B X 


3.1.2. Prepare ultrasonic sensor 


@) The obstacle avoidance algorithm using the ultrasound sensor has not yet been integrated into the 
released code. The following setup provides a start point but is not mandatory. 


®, After Jan.1st, 2021, we include an ODMed ultrasonic sensor with RGB LED in the Nybble kit. It 
doesn't require any soldering, but you need to trim off the clip residue of the connection wire on the 
head's end. 


You can download the demo code at 
https://github.com/PetoiCamp/OpenCatttree/main/Module Tests/testRGBLedUlrasonic 


The tutorial video is at https://youtu.be/kV2U YbpfGic 
The sensor is connected to the NyBoard via a 4 pin cable. 
e Solder on the optional LED to the ultrasonic sensor 


The optional RGB LED can be soldered to the four pins of the ultrasound sensor (instructions) to indicate its 
working status or can be programmed as decorative light. 


Bend the pins of the ultrasonic sensor for later installation. 


e Solder 4-pin ultrasonic sensor header to NyBoard 


The ultrasonic module is connected to the exposed GPIO pins located in the opposite corner of the board 
from the TTL connector. You can customize the pin definitions in OpenCat.h. By default definitions, solder 
the ultrasonic module connection header in the holes labeled “D8 D9 D10 GND” as pictured below. 


GND _ BATT+ AA 


common cathode 
RGB LED 


w 


WSH ID 12131415 
®@EsF 11098 


OpenCat.h 


89 //board configuration E] © 
90 #define INTERRUPT 0 8 
91 Hdefine IR_RECIEVER 4 // Signal Pin of IR receiver 2O 
92 #define BUZZER 5 ed 
93 #define GYRO : e 


94 Hdef ine ULTRA_SOUND 
95 HAdefine BATT AQ 


Oo 


#def ine VCC 


#def ine TRIGGER 9 

#def ine ECHO 10 
01 #def ine LONGEST_DISTANCE 200 // 200 cm = 2 meters 
02 float farTime = LONGEST_DISTANCE * 2 / 0.034; 
03 Hendif 


3.1.3. Trim the servo arms for attaching servos. 


Fr jet 


thigh x 8 <= servo arm | => _neckx1 


Most of the servo arms on the model are trimmed from the cross-shaped arm |. Since there will be more 
unused straight arms, you can practice trimming with them first. 


An alternative method to trimming is using a half-burned knife to cut the plastic parts off. Leave a little bit 
longer because melted plastic will have a rounded edge. 


@ Pay attention to the width difference between servo arm I's two long sides, as well as the trimming 
location (using screw holes as references). 


As we switch servo suppliers, the servo arms also changed a little bit (as shown below). To reduce 
confusion, the servo arm | can be used for most of the joints, just trim it accordingly. Servo arm K is used for 
the tail. Servo J can be omitted. 


For Tail 


For thigh and head 


| @ In kits after January 2021, we included the new servo arms that requires minimal efforts to cut. You 


| only need to cut the cross-shaped servo arm to make the L-shaped connector for the neck joint. 


3.1.4. Assemble the head group. 


Note that the base should only be partially assembled for later calibration. Otherwise, it will be difficult to 
insert the servo between neckpieces. Also, notice how the servo wire is organized in the head. Assemble 
the head group as shown in the head animation. 


@ DO NOT connect the head with the neck yet, because the tilt servo on the head has to be 
calibrated. 


3.2. Body 


3.2.1. Part list 
e NyBoard only 
Note that without the Raspberry Pi, the NyBoard is mounted to the underside of y1 with the servo 


connections facing downward. In later versions, the y1 piece is designed to be symmetric so that both ends 
have two screw holes. 


bas 


Part List 
belly 
ring x4 
mg92b 
mg90d x 
shoulder Xx 
shoulderPi 
Yv1 X 
yv2 
battery holder 
rivet X 


snrine G 


spring H X 
screw D X. 
screw E X 


e NyBoard with Raspberry Pi 


Use y1Pi to replace y1, and add Pi Stand. Pay attention to the location of the pink pieces. Note that with the 
Raspberry Pi, the NyBoard is mounted on top of y1Pi. 


Part List 
belly 
ring x4 
mg92b X 
mg90d X 
shoulder X 
shoulderPi 
y1Pi « 
Pi Stand X 
y2 
battery holder 
rivet x 
spring G 
spring H X 
screw D X 
screw E X 


® On earlier batches of NyBoards, the manufacturer used taller jumper pins than expected, so it will 
be necessary to bend pins or otherwise modify the NyBoard to fit a Pi on top and use the Pi Stand. 
There is a list of suggested solutions in the forum by this link: 
https://www.petoi.com/forum/clinic/placement-of-raspberry-pi-3b 


e Other controllers 
lalso included 5 x 1”/4 nuts for mounting other circuit boards. 


3.2.2. Install the adjustable battery holder to the belly 


Bend the hinge L of the battery holder to 90 degrees, close to the wall. It functions as a switch. Insert the 
long screw E through the rivet so that you can better handle the rivet. Insert and push the rivet into the hole 
on the bottom of the battery holder. Pay attention to the holes! locations. 


a 
id 


The spring attached structure of the battery holder is used for shifting the center of mass when fine-tuning 


gaits. 


® The battery holder is generic for AA (1.5V) batteries. But Nybble uses 3.7V Li-ion batteries. 


3.2.3. Assemble the body group 


Pay attention to the long pins of the infrared receiver and FTDI port. They are designed to be bent in 
favorable directions. Don't bend the pins too often or it will lead to metal fatigue. Observe the adjusted 
configuration if you want to mount a Pi. 
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Assemble the body group as shown in the body animation. 


5 The spine piece may be thicker than the slot on the shoulder. You can insert it from the outside first 
to compress the tip and widen the slot, then insert it to the inside of the shoulder. 


spine 


shoulder 


3.3. Shank 


3.3.1. Part list 


En 


3.3.2. Attach t 


he rubber to the tip of the shank. 


Part List 


shank 
rubber toe 
mg90d 
screw D 


The serrated structure on the tip of the shank is already good for walking. The rubber toe is optional to 
increase friction and soften each step. 


3.3.3. Insert the servo into the slot on the shank. 


X 
Xi 
Xi 
Xt 


LEL As. 


Ake 


Pay attention to the direction that the wire is twisted. The small dent on the long edge is designed to let the 
wire go through. Think about the symmetry of the four legs. Assemble the shank as shown in the shank 


animation. 


@) DO NOT install the servo screw A yet. 


3.4. Thigh 


3.4.1. Part list 


la) Suren 


Dart lict 
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thigh1 x4 


thigh2 x4 
servoarml x8 
spring F x8 
screw C x2 


In later versions, we will use plastic pieces for thigh2. 


3.4.2. Trim the servo arms for attaching servos. 

The location has been shown in the Head and Neck section. The trimmed narrower servo arm is designed 
to be inserted into spring F. 

3.4.3. Assemble the thigh. 


Before closing thigh1 and thigh2, put the wire of the shank through the slot in the middle of the thigh. Think 
about the symmetry of the four legs. 


Pasar. 


Ln 


wire organizer 


The servo arm should be able to slide in the track on thigh2 with subtle friction after thigh1 and thigh2 are 
screwed together. You can tune the tightness of screw C to achieve proper friction. If you need more control 
over the tightness: 


e Scratch the track using a flat screwdriver to reduce friction. 


e Apply a little paper glue to the track and let dry to increase friction. 


Assemble the thigh as shown in the thigh animation. 


® DO NOT screw neck and legs to the body's servos yet. 


3.5. Tail 


3.5.1. Part list 


Part List 
tail1 
tail2 
servo arm K 
rivet X 2 
screw D X 2 


3.5.2. Assemble the tail. 


The screw D is installed in the third hole counted from the center of the servo arm K. Pay attention to the 
order that every piece is stacked. The wheel (tail2) should be able to rotate with little friction, and the whole 


tail should be able to tilt by a small degree. 


DN 


Assemble the tail as shown in the tail animation. 


5 In kits after January, we inlcuded a special servo arm to simplify the installation of the tail joint. 


® DO NOT connect the tail to the body yet. 


4 ss Configuration 


The following video shows the software configuration using our robot dog Bittle. The steps are identical to 
Nybble except that you need to change the model definition in OpenCat.h to Nybble. 


//Hineclude "InstinctBittle.h' //activate the correct header file according to your model 
ES “InstinctNybble.h' 


4.1. NyBoard 


4.1.1. Read the user manual 


Find the version info on NyBoard. Read the user manual for ì î 
‚or (a light revision) accordingly. 


/\ Wrong operations may damage your NyBoard! 
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Servo Cap 
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7.4V Battery socket 


NyBoard V1_0 Bottom side 


4.1.2. Dial the I2C switch (SW2) to Ar. 


The 12C switch changes the master of I2C devices (gyro/accelerometer, servo driver, external EEPROM). On 
default “Ar”, NyBoard uses the onboard ATmega328P as the master chip; On “Pi”, NyBoard uses external 
chips connected throuah the I2C ports (SDA. SCL) as the master chip. 


® Sometimes if you cannot go through the bootup stage, maybe you have accidentally dialed the 
switch to “Pi”. 


® The following section is kept for older versions (VO) 


4.1.3. Dial the potentiometer clockwise to start from the lowest voltage. 


©) From NyBoard VO 2, we provide a jumper selector to bypass the potentiometer. If you 
are using the metal servos in a standard Nybble kit, this section can be skipped. 


Higher voltage will increase the servos’ torque and make Nybble move faster. The downside is it 
will increase current draw, reduce battery life, affect the stability of the circuit, and accelerate the 
wearing of the servos. Based on my tests, 5.5V seems to result in a balanced performance. 


For the initial installation, don't put screws on the NyBoard as you may need to take it out for 
tuning the potentiometer. Make sure all the servos can rotate fine in normal working conditions 
before making fine calibrations. 


4.1.4. Adjust the NyBoard for optimized performance (no need for NyBoard V1 0). 


NyBoard is designed for two use cases. One is for Nybble that uses metal-geared servos, the other 
is for DIY robots that may use plastic geared servos. Plastic servos can only stand 6V so there is a 
step-down chip on NyBoard. The chip is rated for 5A maximal output, but can only be achieved 
with multiple proper settings and careful tuning. 


When using NyBoard with the metal-geared servos of Nybble, optimized performance can be 
achieved by some adjustment. For NyBoard_ VO 1, you will need to do some soldering work as 
discussed in the forum post. For NyBoard_ VO 2, you can connect the jumper switch SW3 
between BATT and V_S (Considering safety for plastic servos, by default NyBoard comes with 
SW3 connecting V_S and V+). 


@ V_S means power for the servo. The jumper switch chooses whether to power the 
servos (V_S) by the step-down chip (V+) or by the batteries (BATT) directly. So BATT 
and V+ should never be connected directly. 


G) Itturns out that NyBoard works more stable when powering the metal-geared servos 
directly with BATT rather than V+. However, if you are using NyBoard to drive your own 
plastic geared servos, you do need to use the step-down circuit. 


4.2. Downloads and installations 


You will need the newest Arduino IDE to set up the environment. Older versions tend to compile 
larger hex files that may exceed the memory limit. 


If you have previously added other libraries and see an error message "XXX library is already installed”, | 
would recommend you delete them first (instruction: https://stackoverflow.com/questions/16752806/how-do- 
i-remove-a-library-from-the-arduino-environment). Due to different configurations of your Arduino IDE 
installation, if you see any error messages regarding missing libraries during later compiling, just google 
and install them to your IDE. 


® If you downloaded the newest OpenCat code from GitHub after Jan 3, 2022, you can skip all the 
following library. 


4.2.1. Install through the library manager 


Go to the library manager of Arduino IDE (instruction: https://www.arduino.cc/en/Guide/Libraries), 
search and install 


e Adafruit PWM Servo Driver 
e QList (optional) 
e IRremote 


The IRremote library was updated recently. And for some reason, they even changed the encoding 
of the buttons. You MUST roll back the library's version to 2.6.1 in the library manager. 


To save programming space, you MUST comment out the unused decoder in IRremote.h. It will 
save about 10% flash! 


Find Documents/Arduinolflibraries/IRremotelsrciIRremote.h and set unused decoders to 0. 
Thatis, only DECODE NEC and DECODE HASH are set to 1, and others are set to 0. 


1 #define DECODE_RC5 0) 
2 #define SEND_RC5 0 
5) 

4 #def ine DECODE _RC6 0) 
5 #define SEND _RC6 0} 
6 

7 #def ine DECODE_ NEC jb 
8 #def ine SEND_NEC IC) 
e) 
10 #def ine DECODE SONY 0) 
11 #define SEND _SONY 0 
12 
USL en 
14 set zeros all the way down the list 
15 500 
16 


17 #def ine DECODE_HASH 1 // special decoder for all protocols 


Install by adding .ZIP library 


Go to jrowberg/i2cdevlib: I2C device library collection for AVR/Arduino or other C++-based MCUs, 
download the zip file, and unzip. You can also git clone the whole repository. 
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Use Add .ZIP Library to find Arduino/MPU6050/ and Arduinol/l2Cdevl/. Click on the folders and 
add them one by one. They don't have to be ZIP files. 


& Arduino Fie Edi 


Weeks 


4 Show Sketch Fokder 
p gdefine OOLEN 10 
bol printiPU = fotse; Elhadaed »_Manage Lbrarles.…. 


Add ZIP Library. 


void sep { raries 
join I2C bus (I2Cdev library doesn't do this outomotia Arlo Maratiee 
6 44f T2ODEV_ IMPLEMENTATION == T2CDEV_ARDUIND..NTRE 
Wire .beginO; 


= 24; // MOM 12C clock CAMMiiz tf CPU is Mit) 
} selif I2CDEV_ IMPLEMENTATION =— I2CDEV_BUILTIN_FASTWIRE 
Fastwire: :setup(40@, erve); 
genau 


Serial „begin(57600); 
Serial „setTimout 5); 
delayC1) 

while C!Sertal);//check here 


SottwareSerlal 


Ardulno File Edi 
. Select à zip file or a taïder containing the Wrary you'd Ike to add 
» Arduino B 
ame __Dste Modified 
B ADSLL1S Wednesday, May B, 2019 12:40 PM 
B ADXLI4S Wednesday, May B, 2019 12-40 PM 
0 AK8963 Wednesday, May B, 2019 12-40 PM 
B AK8975 Wednesday, May 8, 2019 12-40 PM 
B BMALSO Wednesday, May B, 2019 12-40 PM 
Bn amro8s Wednesday, May 8, 2019 12:40 PM 
We 051307 Wednesday, May B, 2019 12-40 PM | 
BB HMC5S43 Wednesday, May B, 2019 12:40 PM 
BB HMCSEBIL Wednesday, May B, 2019 12-40 PM 
B HTU2ID Wednesday, May 8, 2019 12-40 PM 
B Aa2000 Wednesday, May B, 2019 12-40 PM 
we 163200 Wednesday, May 8, 2019 12-40 PM 
we 13642000 Wednesday, May B, 2019 12-40 PM 
 L3GDzon Wednesday, May B, 2019 12-40 PM 
wrs Wednesday, May 8, 2019 12:40 PM 
0 LSM3O3DLHC Wednesday, May B, 2019 12:40 PM 
B MPRI21 Wednesday, May B, 2019 12:40 PM 
B MPUGOSO Wednesday, May B, 2019 12-40 PM 
1 MPU9I5O Wednesday, May B, 2019 12-40 PM 
B M55803 Wednesday, May B, 2019 12-40 PM 
Be SSD1308 Wednesday, May B, 2019 12-40 PM 
B TCA5A24A Wednesday, May 8, 2019 12-40 PM 
File Format: _ ZIP files oe folders B 
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4.2.3. Add NyBoard support to Arduino IDE 


e IfyougetNyBoard V1 *, you can simply choose Arduino Uno. 


& Arduino File Edit Sketch Tools Help A& 301MBFree 100% 5D MD @ 
> ® Writeinstinct - OpenCat.h | Ard: Auto Format 

Archive Sketch 

Fix Encoding & Reload 

Manage Libraries… 
'6alass Motion { Serial Monitor 


"7 _public: Serial Plotter 

’8 byte pins[DOF]); , 

’g int8_t period; \_WiFi101 / WiFiNINA Firmware Updater 

jo int expectedRollPitch[2]; //4 - 

1 byte angleDataRatio; Board: “Arduino Uno" Boards Manager... 

i2 byte loopCycle[3]; ‚Port: “/dev/cu.BittleSPP-877502-Port” > E ; 

; char* dutyAngles; __Get Board Info Arduino AVR Boards Ld Arduino Yún 


a MOtLON(J 4 


Programmer: “"USBtinylSP" 


5) period = 0; 

e expectedRollPitch[0] = 0; Burn Bootloader Arduino Nano 

Á expectedRollPitch[1] = 6; : 

8 dutyAngles = NULL; Arduino Mega or Mega 2560 
Ke) } Arduino Mega ADK 

7) Arduino Leonardo 

Dj int lookupAddressByName(char* skillName) £ Arduino Leonardo ETH 

12 int skillAddressShift = @; Arduino Micro 

13 for (byte s = 0; s < NUM SKILLS; s++) {//save skill info t Arduino Esplora 


4 byte nameLen = EEPROM.read(SKILLS + skillAddressShift++) 
: char* readName = new char[namelen + 1); 


5 Arduino Mini 
6E for (byte 1 = @; 1 < namelen; 1++) { 

17 

} 


Arduino Ethernet 


readName[1] = EEPROM. read(SKILLS + skillAddressShift++ Arduino Fio 
Arduino BT 
raadMamafnamal anl — '\@'- LilyPad Arduino USB 


LilyPad Arduino 


Arduino Pro or Pro Mini 


® The following section is kept for older versions (VO) 


e If you have NyBoard VO * which runs at 20MHZz, you need to add our customized 
configuration file following the next steps: 


Automatic method (many thanks to A-Ron!) 


rome 


(reauses restart of Arduino) 
OE pastsonal Boards Manager URLs 


Show verbose output during: + 


Compiler warnings 


” Display line numbers 
Verify code after upload Use external eartor 
7 Check for updates on startup 7 Save wen verifying or uoloading 


Additional Boards Manager URLs- _hetps://adafruit githetb io /arduino-board-index/package_adafrurt_index.json C° 


[Users /b21/Library/Arduino1 5/ preferences Lut 


1. Open the Preferences... panel 


2. In the Additional Boards Manager URLs field, add 
https:/Iraw.githubusercontent.com/PetoiCamp/OpenCat/masterlResources/INyBoard/bo 
ardManagerlpackage_petoi_nyboard index.json. If there are already URLs listed in this 
field, separate them with commas or click on the icon next to the field to open up an editor and 
add this URL to a new line. Make sure there's no space in the address when you copy-paste 
the link. 


3. Click on the OK button to close the Preferences panel (you have to close the previously 
opened Additional Boards Manager URLs editor first, to close the Preference panel) 


4. Open the Boards Manager... window with the Tools -> Board: XXXX -> Boards Manager... 
menu item. 


‚ In the Filter your search… field, type NyBoard 
‚ Select the entry and click on Install 


. Click on the Close button 


oor CS Kor Kònl 


„ Select ATmega328P (5V, 20 MHz) NyBoard from the Tools -> Board: XXXX menu 
(NyBoardVO 1 and NyBoardVO 2 are using the same board settings.) 


Manual Board Installation Method 


@ Only if the above method fails 


e Locate the file boards.txt 

Mac location: 
/Users/UserName/Library/Arduino15/packages/arduino/hardware/avr/iversion#/ 
Or: 

/Applications/Arduino.app/Contents/Java/hardware/arduino/avr 

To access, right-click on Arduino.app and choose Show Package Contents 
Windows location: 

C:\Program Files(x86)\Arduino\hardware\arduino\avr\ 


IMPORTANT! If you have installed the Arduino IDE via the Microsoft Store, you likely will not have 
access to the folder where critical configuration files are stored. The easiest solution is to uninstall 
the IDE and download/re-install it directly from https://www.arduino.cc. 


Linux 


Downloading from the terminal or from the software manager might not give you the latest version 
which can be an issue. Please download the latest version from Arduino's site: 
https:/www.arduino.cc/en/Main/Software 


Unzip the package and sudo install.sh 

The location of boards.txt files is: 

Fedora: boards.txt is symlinked under: 

letc 

Arch: boards.txt is found at: 
/usr/share/arduino/hardware/archlinix-arduino/avr!/ 
Mint: 

location _of installation/arduino/hardware/arduino/avr 
Ubuntu (on 18.04 when installing with apt-get install arduino): 
/usr/share/arduino/hardware/arduino/boards txt 

after locating boards.txt: 


e Make a copy of boards.txt in case you want to roll back. 


e Create new boards.txt. 

You can download my boards.txt file, or: 

Edit your boards.txt with admin privilege. Find the section of 
pro.name=Arduino Pro or Pro Mini 


and insert the 


1 ## Arduino Pro or Pro Mini (5V, 20 MHz) w/ ATmega328P 

D 

3 pro.menu.cpu.20MHzatmega328=ATmega328P (5V, 20 MHz) NyBoard 
4 

5 


pro.menu.cpu.20MHzatmega328.upload.maximum_size=30720 


7 BFe:menu:epu:20MHzatmega328. uplead: ptduumzdede_size-2048 


9 pro.menu.cpu.20MHzatmega328.bootloader. low_fuses=OxFF 

10 pro.menu.cpu.20MHzatmega328.bootloader.high_fuses=0xDA 

11 pro.menu.cpu.20MHzatmega328.bootloader.extended _fuses=0xFD 

12 pro.menu.cpu.20MHzatmega328.bootloader. filezatmega/ATmega328_20MHz. hex 


14 pro.menu.cpu.20MHzatmega328.bui ld.mcu=atmega328p 
15 pro.menu.cpu.20MHzatmega328.build. f_cpu=20000000L 


17 ## Arduino Pro or Pro Mini (5V, 16 MHz) w/ ATmega328P 


code block in the Arduino Pro or Pro Mini section as below. Save and quit your editor. 


HERRERA HIE RRA BRAHE RAE HAAR 


pro.name=Arduino Pro or Pro Mini 


pro.upload. tool=avrdude 
pro.upload.protocol=arduino 


pro.bootloader.tool=avrdude 
pro.bootloader.unlock_bits=0x3F 
pro.bootloader. lock_bits=0xOF 


OO 0 ND U B WN HH 


ep 
ri © 


pro.build.board=AVR_PRO 


pro.build.core=arduino 


jk 
WN 


pro.build.variant=eightanaloginputs 


en 
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#H Arduino Pro or Pro Mini (5V, 20 MHz) w/ ATmega328P 
HE oenen 
pro.menu.cpu.20MHzatmega328=ATmega328P (5V, 20 MHz) NyBoard 


Ee 
WO MO NN OD 


pro.menu.cpu.20MHzatmega328.upload.maximum_size=30720 


N 
@ 


pro.menu.cpu.20MHzatmega328.upload.maximum_data_size=2048 


No 
[E 


pro.menu.cpu.20MHzatmega328.upload.speed=57600 


NN 
WN 


pro.menu.cpu.20MHzatmega328.bootloader. low fuses=OxFF 


No 
EN 


pro.menu.cpu.20MHzatmega328.bootloader.high_fuses=0xDA 


No 
UI 


pro.menu.cpu.20MHzatmega328.bootloader.extended_fuses=OxFD 


No 
[ep] 


pro.menu.cpu.20MHzatmega328.bootloader. fi lezatmega/ATmega328_20MHz.hex 


NP _N 
0 IN 


pro.menu.cpu.20MHzatmega328. bui ld.mcu=atmega328p 
pro.menu.cpu.20MHzatmega328.build.f_cpu=20000000L 


W W NN 
OO WO 


#H Arduino Pro or Pro Mini (5V, 16 MHz) w/ ATmega328P 
32 HE mennen nen 


e Download ATmega328_20MHz.hex and put it in your Arduino folder „/bootloaders/atmega/. 
You should see other bootloaders with the ‚hex suffix in the same folder. 


Restart your Arduino IDE. In Tools->Boards, select Arduino Pro or Pro Mini. You should find 
ATmega328P (BV, 20 MHz) in the Processor menu. 


case BehPE2O: PTS 
case @IPEZID: PTIC 
case @FF2200: PTLFC 
case @xFFO2ED: PTLFC >> 1"); 
case OFFCZID: PTIFC” »11°); 
case @APERF: PIC rete CPCbwatip”D), 
case @HFANS7: PTLFC +"); î 

case BFPOGE: PTIFC EY), revam (FC'pee”)); 

case @FFEENT: PTLEC 0"); return (FC'UL"ID; 

case @FFIBE7: PTLFC 108,3; return (FCI; 


D If you cannot find the board, your Arduino IDE may be using the boards.txt in another 
path. Search boards.txt in all the folders on your computer. Find out the right file that's in 
effect. 


® Only if the bootloader of NyBoard collapsed, which is very unlikely to happen 
4.2.4. Burn the bootloader 
What is a bootloader? 


Every NyBoard has to go through functionality checks before shipping, so they should already 
have a compatible bootloader installed. However, in rare cases, the bootloader may collapse then 
you won't be able to upload sketches through Arduino IDE. 


Well, its not always the bootloader if you cannot upload your sketch: 


e Sometimes your USB board will detect a large current draw from a device and deactivate the 
whole USB service. You will need to restart your USB service, or even reboot your computers; 


e You need to install the driver for the FT DI USB 2.0 to the VART uploader; 
e You haven't selected the correct port; 
e Bad contacts; 
e Bad luck. Tomorrow is another day! 
If you really decide to re-burn the bootloader: 


e If you get NyBoard V1 *, you can simply choose Arduino Uno under the Tool menu of 
Arduino IDE. 


e If you have NyBoard VO _* which runs at 20MHZz, you need to choose NyBoard 
(ATmega328P 5V, 20MHz). 


Pr). The above screenshot shows two popular 
ISP is a cheap bootloader you can buy, while the 
se a regular Arduino as ISP! 


port on NyBoard. Notice the direction when connecting. 
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B ng so, wait patiently until you see several percent bars 
pp up for one minute. 


4.2.5. Connect FTDI uploader 


Check the pin marks of the uploader. They should match the marks on the NyBoard. 
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On the red board, the jumper selector should be put on 5V (not 3.3V) on the uploader for Arduino. 
Match the GND on both the uploader and the 6-pin socket on NyBoard. 


Connect your computer with the FTDI uploader through mini-USB to USB cable. The uploader 
has three LEDs, power, Tx, and Rx. Right after the connection, the Tx and Rx should blink for one 
second indicating initial communication, then dim. Only the power LED should keep lighting up. 
You can find a new port under Tool->Port as “/dev/cu.usbserialvooooxxx” (Mac) or “COM#” 
(Windows). 


For Linux, once the uploader is connected to your computer, you will see a “ttyUSB#" in the serial port list. 
But you may still get a serial port error when uploading. You will need to give the serial port permission. 
Please go to this link and follow the instructions: https://playground.arduino.cc/Linux/All/#Permission 


& Arduino File Edit Sketch Tools Help 


Auto Format E3MBno 1.83.10 Hourly Build 2019/04/18 12: 
Archive Sketch 

Fix Encoding & Reload 

Manage Libraries… 

Serial Monitor 

Serial Plotter 


int distance = duration * @ 


19 WiFi101 / WiFiNINA Firmware Updater 
20 // Prints the distance on t/ 


21 Kl OEL EPEN Board: "Arduino Pro or Pro Mini” 

Á een eegerdn ° Processor: "ATmega328P (5V, 20 MHz) NyBoard" 

eN Port: “/dev/cu.usbserial-00000000” Serial ports 

25 __meowO; Get Board Info /dev/cu.Bluetooth-Incoming-Port 
26 } 5 5 E /dev/cu.MALS 

27 Programmer: "USBtinylSP Idev/cu.Nybble1-SPPDev 
28Evoid loop) { Burn Bootloader Idev/cu.SOC 

29 _ float voltage = analogRead(BATT); 35 — ETE 

30 Le (voltage: wi Ee U 8, 8, 25, 2 v [dev/cu.usbserial-00000000 


31 #ifdef NyBoard_V@_1 
740 


33 #else 
34 300 


If Tx and Rx keep lighting up, there's something wrong with the USB communication. You won't see the new 
port. Is usually caused by overcurrent protection by your computer, if you're not connecting NyBoard with 
an external power supply and the servos move all at once. 


In later versions, there may be a different version of the FT DI uploader. Just check the marks on the chip and 
connect it with NyBoard correctly. 


®, If you cannot find the serial port after connecting to your computer, you may need to install the 
driver for the CH340 chip. 


e Mac 


e Windows 


4.2.6. Connect Bluetooth uploader (optional) 


I's possible to program and communicate with Nybble wirelessly. Check out the Bluetooth instruction on the 
OpenCat forum. You can even control Nybble with a smartphone APP or web API from there! 


Starting from Jan.1st, 2021, we include our official Bluetooth dongle in the standard Nybble kit. It can be 
used for wirelessly uploading sketches and communicating with the robot. The default passcode is 0000 or 
1234, and the baud rate is set to 115200. After connecting to the computer, you can use it in the same way 
as the wired uploader. 


Status LED (red) 
Blink: waiting for pairing 
Off: paired 

Stable: communicating 


baaseeten 


Communication pins 


purddeedd 
aansaant 


® You will need to set its baudrate to 57600 to use it on NyBoard VO *. 


Connect the Bluetooth dongle to the wired uploader (+5V, GND, Rx to Tx, Tx to Rx), and send 
AT+BAUD7 through the serial monitor with the setting Both NL & CR and baudrate 115200. 


@) On Mac, the Bluetooth may lose connection after several uploads. In that case, delete the 
connection and reconnect to resume its functionality. 


4.2.7. Download the OpenCat package 


e Download a fresh OpenCat repository from GitHub: https://github.com/PetoiCamp/OpenCat. It's better if 
you utilize GitHub's version control feature. Otherwise, make sure you download the WHOLE OpenCat 
FOLDER every time. All the codes have to be the same version to work together. 


e If you download the Zip file of the codes, you will get an OpenCat-main folder after unzipping. You need 
to rename it to OpenCat before opening the OpenCat.ino. 


® No matter where you save the folder, the file structure should be: 


OpenCat/ 
/OpenCat.ino 
/Writelnstinct/ 
/Writelnstinct.ino 
/OpenCat.h 
/instinctBittle.h 
/InstinctNybble.h 


e There are several testX.ino codes in ModuleTests folder. You can upload them to test certain modules 
separately. Open any testX.ino sketch with prefix “test”. (l recommend using testBuzzer.ino as your first 
test sketch) 


e Open up the serial monitor and set up the baudrate: 
e For NyBoard V1 * choose the board as Arduino Uno and later set the baudrate to 115200 in both 


the code and the serial monitor. 


e For NyBoard VO * choose the board as NyBoard (ATmega328P 5V, 20MHz) and later set the 
baudrate to 57600 in both the code and the serial monitor. 


e Compile the code. There should be no error messages. Upload the sketch to your board and you should 
see Tx and Rx LEDs blink rapidly. Once they stop blinking, messages should appear on the serial 
monitor. 


e Make sure you set “No line ending” to before entering your commands. Otherwise, the invisible \n' or \\r 
characters will confuse the parsing functions. 


Writelnstinct 


49 ee /dev/cu.usbserial-A7005e3Z 
51 Send 


53 / I2Cdev/S 
54 include <* OpenCat Writing Constants to EEPROM... 
55 include «Reset all joint calibration? (Y/n) 


56 include 4 


57 * Do you need to update Instincts? (Y/n) 
58 AAI 
59 /Change 4 
69 nt discaf 


Autoscroll Yv No line ending ; 


Newline 
Carriage return 
Both NL & CR 


57600 baud Clear output 


Arduino Pro or Pro Mini, ATmega328P (SV, 20 MHz) on /dev/cu.usbserial-A7005e 32 


For Linux machines, you may see the following error message: 


You will need to add execution privilege to the avr-gee to compile the Arduino sketch: sudo chmod +x 
filePathToTheBinFolder/bin/avr-gcc 

Furthermore, you need to add execution permission to all files within /bin, so the command would be : 
sudo chmod -—R +x /filePathToTheBinFolder/bin 


4.3. Arduino IDE as an interface 


With the FTDI to USB converter connecting NyBoard and Arduino IDE, you have the ultimate interface to 
communicate with NyBoard and change every byte on it. 


| have defined a set of the serial communication protocols for NyBoard: 


OpenCat 
Communication Protocol and Parsing 


tarte olen 
print help information 


| Format 
der | 
‘\n' string strlen +2 [calibrate servoig by angle 

idx*‚angle** ‘\n' string strlen +2 [move servoig to angle 

| char 1 show all 16 joint angles 
| char shut down servos 
0 

char 


Bytes Function 


DN 


taspi | Monitor pause motion 


erial 
>ort 


abandon calibration 


save calibration 


char | 
|__abbreviation _ | \n'| string | strlen +2 [load skill 
command | \n'| string | strlen +2 [some future command words 
‚ idx | an Jide} an || string | strien +2 list of indexed rotation angles 
md a la | … |aooe}”| string | DoF+2 list of all Dof rotation angles 


r 


index range: 0 * (Dof - 1) 


* angle range: -90 * 90. fits in the range of signed char (-128 * 127). Also depends on the servos’ parameters 


All the token starts with a single Ascii encoded character to specify its parsing format. They are case- 
sensitive and usually in lower case. 


| ® Some tokens haven't been implemented, such as 'h'. Token í' and 'I' still have some bugs. 


4.4. Raspberry Pi serial port as an interface 


® Only when using Pi as a master controller. Nybble doesn't need a Pi to move. 


You need to disconnect the serial uploader to communicate with Pí's serial port. 


As shown in the serial protocol, the arguments of tokens supported by Arduino IDE's serial monitor are all 
encoded as Ascii char strings for human readability. While a master computer (e.g. RasPi) supports extra 
commands, mostly encoded as binary strings for efficient encoding. For example, when encoding angle 65 
degrees: 


e Ascii: takes 2 bytes to store Ascii characters '6' and '5' 


e Binary: takes 1 byte to store value 65, corresponding to Ascii character 'A' 


@, What about value -113? It takes four bytes as an Ascii string but still takes only one byte in binary 
encoding, though the content will no longer be printable as a character. 


Obviously, binary encoding is much more efficient than the Ascii string. However, the message transferred 
will not be directly human-readable. In the OpenCat repository, | have put a simple Python script 
ardSerial.py that can handle the serial communication between NyBoard and Pi. 


4.4.1. Config Raspberry Pi serial port 


In Pi's terminal, type sudo raspi-config 


Under the Interface option, find Serial. Disabled the serial login shell and enable the serial interface. 


(@) A good tutorial on Instructable 


If you plug Pi into NyBoard's 2x5 socket, their serial ports should be automatically connected at 3.3V. 
Otherwise, pay attention to the Rx and Tx pins on your own Al chip and its voltage rating. The Rx on your 
chip should connect to the Tx of NyBoard, and Tx should connect to Rx. 


Á\ You also need to DISABLE the 1-wire interface of Pi to avoid repeating reset signals sent by Pi's 
GPIO 4. 


4.4.2. Change the permission of ardSerial.py 

If you want to run it as a bash command, you need to make it executable: 
chmod +x ardSerial.py 

You may need to change the proper path of your Python binary on the first line: 


#l/user/bin/python 


4.4.3. Use ardSerial.py as the commander of Nybble 


@ NyBoard has only one serial port. You need to UNPLUG the FTDI converter if you want to control 
Nybble with Pí's serial port. 


Typing ./ardSerial.py <args> is almost equivalent to typing <args> in Arduino's serial monitor. For 
example, ./ardSerial.py ker means “perform skill crrawl”. 


Both ardSerial.py and the parsing section in OpenCat.ino need more implementations to support all the 
serial commands in the protocol. 


® Reduced motion capability may happen when connected to Pi! A stronger battery is needed. 


With the additional current drawn by Pi, Nybble will be less capable for intense movements, such as trot (the 
token is ktr ). The system is currently powered by two 14500 batteries in series. You may come up with 
better powering solutions, such as using high drain 7.4 Lipo batteries, or 2S-18650. There are a bunch of 
considerations to collaborate software and hardware for balanced performance. With Nybble's tiny body, it's 
better to serve as a platform for initiating the communication framework and behavior tree rather than a 
racing beast. 


4.5. Battery 


Though you can program NyBoard directly with the FT DI uploader, external power is required to drive the 
servos. 


When powering the NyBoard with only USB FTDI, there's obviously charging and uncharging in the servo's 
capacitor and cause the yellow LED to pulse. However the USB's current is not sufficient to keep the servos 
working. The servo circuit has to be powered by external batteries to work properly. 


4.5.1. Voltage 


NyBoard requires 7.4-9V external power to drive the servos. On Nybble, we are using the 8V standard to 
configure all the parameters as a whole system. That's usually two Li-ion or Li-poly batteries connected in 
series. A single battery is 4.2V when fully charged and can work normally until voltage drops to 3.6V. That's 
about 7.2V with two batteries connected in series. Before installation, dial the potentiometer on NyBoard 
clockwise to try minimum output first (about 4.5V), then dial it up until it can make the robot work properly. 
With our kit servos, it actually works better to connect SW3 between BATT with V_S directly and bypass the 
step-down chip (so no need to tune the potentiometer). 


When looking for batteries, search for keywords “14500 3.7V li-ion battery unprotected”. l've noticed that the 
overcurrent protection of some batteries could be triggered by peak current draw-(usually >2.5A), causing 
NyBoard to reset or malfunction. Try to find batteries with higher discharge ratings. 


Read this forum post to find batteries that work on Nybble. 


4.5.2. Dimensions 


The included battery holder is sized for 14500 batteries, which is 14 mm in diameter, and 50 mm in length. 
50 + 1 mm should still fit in. They are the same size as AA batteries, but much more powerful. Make sure 
not to use them in regular AA devices. If you are in the US, we have tested with EBL 14500 li-ion 
batteries. 


You can also design other battery holders to carry larger batteries for better performance. That's especially 
necessary if you mount a Raspberry Pi or want Nybble to run faster. 
4.5.3. Connection 


Be careful with the polarity when connecting the power supply. Make sure you can find the positive (+) and 
negative (-) sign on both the NyBoard's power terminal and your power supply. 


| Á\ Reversed connection may damage your NyBoard! 


Loosen the screws of the power block. Insert the wires of the battery holder then tighten the screws. When 
turning the switch on, both the blue LED (for the chip) and the yellow LED (for servo) should lit up. 
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In the kit shipped after Jan.1st, the terminal is replaced with an anti-reverse socket, so you won't be able to 
plug in the wrong direction. 
4.5.4. Battery life varies according to usage 


It can last hours if you're mainly coding and testing postures, or less than 30 mins if you keep Nybble 
running. 


When the battery is low, the yellow LED will blink slowly. Although NyBoard can still drive one or two 
servos, it will be very unstable to drive multiple servos at once. That will lead to repeatedly restarting the 
program or awkward joint rotations. In rare cases, it may even alter the bits in EEPROM. You will need to 
reupload the codes and re-save the constants to recover. 


4.5.5. Charging 


You will need compatible smart chargers for the batteries. Keep batteries attended during charging. 


4.5.6. After use 


After playing, remember to remove the batteries from the battery holder to avoid over-discharging. 


4.5.7. Signal interference 


It's ok to connect both FT DI and battery at the same time. You can type in serial commands while the battery 
is connected. | do notice that the USB serial port could be disabled randomly. | think that's due to the sudden 
current draw by servos. It will trigger the computer's overcurrent protection and disable the USB port. In that 
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5 Connect Wires 


“Everything is connected.” [ 


5.1. Joint map 


Nybble's servos are connected to NyBoard's PWM pins symmetrically and resemble the nerves along the 
spinal cord. Though Nybble doesn't have shoulder roll Dof, those indexes(4-7) are reserved for the full 
OpenCat framework. 


Joint Indexes of Nybble 


13 14 
®, NyBoard VO *and V1 *have different PWM pin orders, but the physical servo connection 


remains the same. All adjustments are handled in the software. You don't even need to read the 
pin numbers on the PCB board. 


Use h for the head, tfor the tail, r for shoulder roll joint, s for shoulder pitch joint, k for knee joint, F for the 
front, H for hind, L for left, R for right, the full joints map of OpenCat is: 


Joint Map of OpenCat VO _1 
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Joint Map of OpenCat VO_2 
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Encoding Joint Index: 014 | 2 3 4 1 5016 751480 97 400 A1 42: 43 114 45 Virtual 
Array PWM Pin 4 Sn BAIN A 12N MS 2e 1Sn PONG 1e 145 59 7 O0 15 8 Hardware 


5.2. Plug in the servos 


Observe the indexing pattern to connect servos with correct PWM pins. Be careful with the wires’ direction. 
The brown wire of the servo is GND, while the GND on NyBoard VO 1 is along the centerline. In later 
versions of NyBoards, they are opposite. 
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(NyBoard VO_1 Front) (NyBoard VO_1 Back) 


A quick check is that all On NyBoard VO 1 the brown wires should be far away from the board surface. On 
NyBoard VO 2 the brown wires should be close to the board surface. 
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@, From NyBoard VO 2, the location of servo wires will still be the same, but their direction of colors 


will be opposite 


NyBoard vo_2 
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NyBoard VO_2 
Even though the PCB layouts vary on different NyBoards, the wiring pattern is the same. You don't need to 


read the indexes of the servo pins when plugging the servos. The joint mapping is done automatically in the 
OpenCat code. You just need to select the right board version when uploading the code. 
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Wiring pattern of NyBoard V1_0 


5.3. Wiring 


After calibration, troubleshooting and final assembling, Its time to think about wiring routes to make Nybble 


look neat. There are multiple slots on the frame designed as a wire organizer. Feel free to develop your own 
style for connecting future accessories. Make sure the wires don't get in the way of the servos' movement. 


Below is my wiring routes. 


NyBoard alone 


NyBoard with Raspberry Pi 


5.4. Connect Ultrasonic Sensor (optional) 


If you have not already, plug in the 4 pin cable, make a note of which cable colors are attached to which 
signals. When looking into Nybble's eyes, the connections from left to right are: 


VEC Trigger Echo Ground 


Connect the other end of the cable to the header you soldered in place earlier in assembly. Use the 
following mapping 


Sensor Side NyBoard Side 


Vec D8 


Trigger D9 
Echo D10 
GND GND 


6 Ù Calibration 


“A miss is as good as a mile.” [ 


@ Calibration is vital for Nybble to work properly. 


In previous sections, we have prepared those body parts, but haven't screwed them onto servos. If we don’t 
calibrate the servos before attaching them, they may rotate to any direction, get stuck, and cause damage to 
either the servos or body parts. 


The calibration has four steps: 


1. Write constants to the board 
2. Power on the circuit, let servos rotate freely to zero angle/calibration state 
3. Attach body parts to the servos 


4. Fine-tune the offsets in software. 


The logic behind calibration can be found on the OpenCat forum. 


6.1. Write constants 


6.1.1. There are three types of constants to be saved to NyBoard: 


1. Assembly related definitions, like joint mapping, rotation direction, sensor pins. They are pretty fixed and 
are mostly defined in OpenCat.h. They are even kept consistent with my future robots; 


2. Calibration related parameters, like MPU6050 offsets and joint corrections. They are measured in 
realtime and are saved in the onboard EEPROM. They only need to be measured once; 


3. Skill related data, like postures, gaits, and pre-programmed behaviors. They are mostly defined in 
Instinct.h. You can add more customized skills too. 


6.1.2. Upload and run Writeinstinct.ino. 


The role for Writeinstinct.ino is to write constants to either onboard or I2C EEPROM, and save calibration 


es - 


® You need to change the *on #def ine NyBoard_Vx_x in Instinct.h to match your NyBoard's 
version. The version number is to the left of the green battery terminal. 


® Before uploading the sketch, make sure to close all opened windows of the serial monitor. 
Otherwise, the serial port may be occupied and the sketch will not be uploaded. 


® You also need to dial the slide switch on NyBoard to Arduino rather than Pi! 
After finish uploading WriteInstinct.ino, open the serial monitor. 


® Make sure to set the serial monitor as 115200 baud rate and no line ending. 


ee [dev/cu.usbserial-0001 


Send 


2 Autoscroll Show timestamp No line ending 115200 baud Clear output 


You will see several questions: 
Reset all joint calibration? (Y/n) 


If you have never calibrated the joints, or if you want to recalibrate the servos with a fresh start, type ‘Y’ to the 
question. The ‘Y' is CASE SENSITIVE! 


Do you need to update Instincts? (Y/n) 


If you have modified the Instinct.h in any way, you should type ‘Y’. Though it's not always necessary once 
you have a deeper understanding of memory management. 


Calibrate MPU? (Y/n) 


If you have never calibrated the MPU6050, i.e. the gyro/accelerometer sensor, type ‘Y’. 


Sometimes the program could hang at the connection stage. You can close the serial monitor and reopen it, 
or press the reset button on NyBoard, to restart the program. 


De /dev/cu.Nybble-DevB 
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6.2. Enter calibration mode 


The calibration state is defined as the middle point of the servo's reachable range. Calibration for servos can 
be done in either WriteInstinct.ino or OpenCat.ino. | recommend you do it with WriteInstinct.ino in case 
there's something wrong with the constants. 


You MUST plug in all the servos and batteries for proper calibration. Then in the serial monitor, type ‘c' to 
enter calibration mode. The servos should rotate one by one with unnoticeable time intervals then stop. 
Depending on their initial shaft direction, some may travel larger angles until stopping at the middle point. 
There will be noise coming from the gear system of the servos. You will see the calibration table: 


1; 2, 3, 4, Dj 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
„1 „1 sl -1 „1 el =1 „1 sl =1 „1 el, =1 sl „1 


In 

d 1 | 1 1 1 
0 1 2 3 4 5 6 7 8 9 

e 0 1 2 3 

le) 


et 


Initial values are “-1” or “0”, and should be changed by later calibration. 


@, The servos are using a potentiometer in the feedback loop for position control. When holding at a 
static position, they tend to vibrate around the target angle. A Parkinson's-like vibration will 
develop after a short period of use. It won't affect much during continuous motion. Better servos 


without these troubles could cost 10 times more, so replacing a failed unit is a more cost-effective 
solution. 


6.3. Attach head, tail, and legs. 


6.3.1. Coordinate system 


After entering ‘c', with all servos rotated to their zero angles, now attached the head, tail, and legs prepared 
in the previous section to the body. They are generally perpendicular to their linked body frames. Avoid 
rotating the servo shaft during the operation. 


Rotating the limbs counter-clockwise from their zero states will be positive (same as in polar coordinates). 
The only exception is the tilt angle for the head. It's more natural to say head up, while it's the result of 
rotating clockwise. 


Zero Angle/Calibration State 


* DON'T install limbs without first-time calibration 
* Type ‘c' in serial monitor to start calibration 

* _Attach limbs closest to calibration state 

* _‘c8 6’ means calibrate 8'® servo to 6° 

* Use the included ‘l/ Tuner for parallel reference 
REMEMBER to type ‘s’ to save your calibration 


Positive direction 


6.3.2. Understand the angle divisions 


If we take a closer look at the servo shaft, we can see it has a certain number of teeth. That's for attaching 
the servo arms, and to avoid sliding in the rotational direction. In our servo sample, the gears are dividing 
360 degrees to 20 sectors, each taking 18 degrees. That means we cannot always get exact perpendicular 
installation. But try to get them as close as possible to their zero states. Use screw A to fix the limbs onto 
servos. 
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6.4. Find and save calibration offsets 


6.4.1. Fine-tune the calibration on the software side 


The command for calibration (refer to the serial communication protocol for NyBoard) is formatted as 
cIndex Offset .Notice that there's a space between Index and Offset. 


For example, c8 6 means giving the 8th servo an offset of 6 degrees. Find the best offset that can bring 
the limb to the zero state. 


@ If you find the absolute value of offset is larger than 9, that means you are not attaching the limb 
closest to its zero state. T hat will result in a decreased reachable range of the servo on either side. 
Take off the limb and rotate it by one tooth. It will result in an opposite but smaller offset. 


For example, if you have to use -13 as the calibration value, take the limb off, rotate by one tooth then attach 
back. The new calibration value should be around 5, i.e, they sum up to 18. Avoid rotating the servo shaft 
during this adjustment. 


Preferable 


After calibration, remember to type ‘s’ to save the offsets. Otherwise, they will be forgotten when exiting the 
calibration state. You can even save every time after you're done with one servo. 
6.4.2. ‘L’ shaped joint tuner 


When watching something, the observation will change from different perspectives. That's why when 
measuring length, we always want to read directly above the ruler. 


I's especially important that you keep a parallel perspective when calibrating Nybble. Use the 'L' shaped 
joint tuner as a parallel reference to avoid reading errors. Align the tips on the tuner with the center of the 
screws in the shoulder and knee joints, and the little hole on the tip of the foot. Look along the co-axis of the 
centers. For each leg, calibrate shoulder servos (indexed 8-11) first, then the knee servos(indexed 12-15). 
When calibrating the knee, use the matching triangle windows on both the tuner and shank to ensure 
parallel alignment. 


Perspective window for parallel alignment 


| 
ME EEE" 
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6.4.3. Validation 


After calibration, type ‘d' or ‘kbalance' to validate the calibration. It will result in Nybble symmetrically moving 
its limbs between rest and stand state. 


calibrate 


stand 


6.4.4. Center of mass 


Try to understand how Nybble keeps balance even during walking. If you are adding new components to 
Nybble, try your best to distribute its weight symmetrically about the spine. You may also need to slide the 
battery holder back and forth to find the best spot for balancing. 


7 0 Play with Nybble 


“You can't direct the wind, but you can adjust your sails” 0 


7.1. Control with Arduino IDE 


Try the following serial commands in the serial monitor: 


e “ksit” 

e “mO 30” 

e “mO -30” 
e “kbalance” 
e “kt” 

e “kil” 

e “d” 


® The quotation mark just indicates that they are character strings. Don't type quotation marks in the 
serial monitor. 


7.2. Control with Infrared remote 


7.2.1. Keymap 


Only the position of the buttons matters, though those symbols can help you remember the functionalities. 
I'm going to define position related symbols to refer to those keys. 


I'm using abbreviations for key definitions to reduce SRAM usage. Due to the limited keys of a physical 
remote, |l always change the definitions for fun. 


® The following map is just an illustration. Check function String translatelR(){….} in OpenCat.ino 
for the actual key definitions in effect. They are also open to your customization. 


rest der Byro * Rest puts the robot down and shuts down the servos 
* _Pressing F/L/R will make the robot to move 
balance forward/left/right 


* _B will make the robot move backward 


shutdown : en 
Eee calibrate * Calibrate puts the robot into calibration posture and turns 


off the gyro 
stepping crawl walk * Stepping lets the robot step at the original spot 
* _Crawl/walk/trot are gaits that can be switched and 
trot sit stretch combined with the direction buttons 
* Buttons after trot are preset postures or other skills 
greeting push up pee * _Gyro will turn on/off the gyro for self-balancing. Turning of! 
the gyro can accelerate and stabilize the slower gaits. But 


look up butt up aen it's NOT recommended for faster gaits such as trot. 


We also made a customized remote panel for future batches. Previous users can download the design file 
and print it on A4 paper. 


9 newPanel.pdf 2MB 
PDF 


dt R' 


SOVDDSDOE) 
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7.2.2. Check out the following featured motions 


e Rest puts the robot down and shuts down the servos. It's always safe to click it if Nybble is doing 
something AWKWARD. I'm serious. There are still some ghosts in the system | don’t fully understand. 


e Balance is the neutral standing posture. You can push Nybble from the side, or make it stand up will 
hind legs and tail. You can test its balancing ability on a fluctuating board. Actually balancing is 
activated in most postures and gaits. 


e Pressing FILIR will make the robot move forward/left/right 


e Barras he FERELYRL BEKMAN posture and turns off the gyro 


e Stepping lets the robot step at the original spot 
e Crawl/walk/trot are the gaits that can be switched and combined with the direction buttons 
e Buttons after trot are preset postures or other skills 


e Gyro will turn on/off the gyro for self-balancing. Turning off the gyro can accelerate and stabilize the 
slower gaits. But it's NOT recommended for faster gaits such as trot. 


e Lift Nybble at the middle of its spine so that all its legs can move freely in the air. Click all the buttons on 
the IR remote to see what they do. Then put Nybble on a wide flat table and try those buttons again. 
Different surfaces have different friction and will affect walking performance. The carpet will be too 
bushy for Nybble's short legs. It can only crawl (Command ker) over this kind of tough terrain. 


e You can pull the battery pack down and slide along the longer direction of the belly. That will tune the 
center of mass, which is very important for walking performance. Otherwise, it may keep falling down. 


e When Nybble is walking, you can let it climb up/down a small slope (<10 degrees) 


e Whatever Nybble is doing, you can lift it vertically, and it will stop moving, just like a cat scruffed on the 
neck. 


Buzzer beep meaning: 


ound type [Occasion _______________|Explaination 
hort melody Power up or reboot The program starts successfully 


hort beep The program receives a command 


'epetitive 3 beeps [During use and pausing the movements | The battery is low or unconnected 


5 e If Nybble keeps beeping after you run OpenCat.ino, with numbers printed in the serial monitor, 
it's the low voltage alarm being triggered. You need to power NyBoard with two 3.7V Li-ion/Li- 
poly batteries to pass the threshold. 


e “FIFO overflow! Using last reading!” in the serial monitor is an algorithmic fix to the original 
MPU6050 library. It's not a bug. 


e The servos are designed to be driven by internal gears. Avoid rotating the servos too fast from 
outside. 


e Don't keep Nybble walking for too long. That will overheat the electronics and reduce the 
servos' life span. If you have NyBoard VO _1 (our oldest version), lts possible to reconfigure it 
to make Nybble more stable. 


e Sometimes the program may halt due to voltage fluctuation. Check if the battery is running low 
(< 3.5V each or <7.0V in series). Press the reset button on NyBoard to restart the program. 


e Nybble has acrophobia! If you lift it and rotate it over a certain degree, its current movement 
will be interrupted. Don't flip Nybble over to scare it! 


e Be kind as if you were playing with a real kitten. (“=92D=/) 


8 UU Teach Nybble New Skills 


“Give a cat a fish and you feed it for a day. Teach a cat to fish and you feed it for a lifetime” 0 


8.1. Understand skills in InstinctNybble.h. 


Programmable Gaits and Behaviors 
=— Make full use of every byte, down to nybble and bit! 


Arduino Sketch 


Instruction 


Data 


Button/ remote Posture Single frame of joint parameters Initialization 
Calibration 
: Gait Periodic fra f post 
Arduino IDE je ki Ve Constant Loading 
Bluetooth VART P et oi finalized? aars 
Raspberry Pi Instinct Newbility Adaption 
Serial Status reporting 


Master Arduino 


convoler mio: EN 


etc. 


_ Stringtoken — 
RS AE RE 


has external 


register 


Sensor Effector el address ä 


Arduino Uno 5V 14 16 MHz 0 
ATmega328P 
NyBoard VO 5V+3.3V S5V+3.3V 11 20 MHz 8KB 
EN En En een 
gyro _ derivative |___PCA9685 | Skill, Skill, 5 Skill, 
acceleration Ë Final Motion — Skill, 


EEPROM has limited (1,000,000) write cycles. So | want to minimize the write operations on it. 


There are two kinds of skills: Instincts and Newbility. The addresses of both are written to the onboard 
EEPROM(1KB) as a lookup table, but the actual data is stored at different memory locations: 


e I2C EEPROM (8KB) stores Instincts. 


The Instincts are already fine-tuned/fixed skills. You can compare them to “muscle memory”. Multiple 
Instincts are linearly written to the I2C EEPROM only once with Writelnstinct.ino. Their addresses are 
generated and saved to the lookup table in onboard EEPROM during the runtime of WriteInstinct.ino. 


e PROGMEM (sharing the 32KB flash with the sketch) stores Newbility. 


A Newbility is any new experimental skill that requires a lot of tests. Its not written to the 12C nor onboard 
EEPROM, but the flash memory in the format of PROGMEM. It has to be uploaded as one part of the 
Arduino sketch. Its address is also assigned during the runtime of the code, though the value rarely changes 
if the total number of skills (including all Instincts and Newbilities) is unchanged. 


8.2. Example InstinctNybble.h 


//a short version of Instinct.h as example 


#define WalkingDOF 8 
#def ine NUM_SKILLS 4 
#def ine I2C_EEPROM 


const char rest[] PROGMEM 
1 OOS 

SOS AO SS SGOOL GO OO 45 AS AAO 
10 const char zero[] PROGMEM 
ae cn 

1 OO A Op Op Oy Oy Op On O5 On Or Oo Or Oo Oo Oke 
13 

14 const char cr[] PROGMEM = { 

15 26, 0, -5, 1, 

16 SS STA AOr In LSI AS Ds 

17 40, 28,-42,-59,-24,-28, -4, 12, 

18 

19 33, 39,-47,-51,-22,-32, -3, 11, 

20) JP 

Dil 

22 const char pul[] PROGMEM = { 

23 -5, 0, -15, 1, 


OO O0 NDW B WN HH 
1 
EN 


u 
a 


ze en Ee 
25 30, 30, 0, O0, 0, 0, O0, 0, 60, 60, 70, 70, 15, 15, -70, -70, 
26 0, -40, O0, 0, 0, 0, O0, OO, 30, 30, 95, 95, 60, 60, -70, -70, 
ld 5, 5, ©, 0, 0, 0, 0, O, 75, 75, 55, 55, -50, -50, -75, -75, 
28 5, 5, ©, O0, 0, ©, O0, ©, 75, -70, 55, 55, -50, 70, -75, -75, 
29 60, -30, -45, O, O0, 0, O0, O, 70, -70, 55, O, -30, -45, -75, -45, 
30 }; 

31 

32 #if !defined(MAIN_SKETCH) || !defined(12C_EEPROM) 


33 const charx skillNamewWithTypell = 
SAR Er Tp res zZenoNMEN: 


35 const char* progmemPointer[] 


5 Ker Pp Eer Zere J8 

37 Helse 

38 const char* progmemPointer[] 
39 #endif 


{zero}; 


8.2.1. Defined constants 

define WalkingDOF 8 

defines the number of DoF (Degree of Freedom) for walking is 8 on Nybble. 
def ine NUM SKILLS 4 


defines the total number of skills is 4. It should be the same as the number of items in the list const 


charx skillNameWithTvnel 1 
define I2C EEPROM 


Means there's an I2C EEPROM on NyBoard to save Instincts. 


® If you are building your own circuit board that doesn't have it, comment out this line. Then both 
kinds of skills will be saved to the flash as PROGMEM. Obviously, it will reduce the available flash 
space for functional codes. If there were too many skills, it may even exceed the size limit for 
uploading the sketch. 


8.2.2. Data structure of skill array 


One frame of joint angles defines a static posture, while a series of frames defines a sequential postures, 
such as a gait or a behavior. Observe the following two examples: 


1 const char rest[] PROGMEM = { //posture 
HO Oeds 

Se On Ey Ey Sg Sg B GN Ng Ei LE 
4 

5 const char cr[] PROGMEM = { //gait 
EAO A 

Ú So Mg toper AE En A2 

8 40, 28,-42,-59,-24,-28, -4, 12, 

ONEN: 

10 33, 39,-47,-51,-22,-32, -3, 11, 

Ibi jee 


They are formatted as: 


Expected 
Total # Body 


of Orientation 


Frames Roll 


Indexed Joint Angles 


els | EAEAESETESEESE 
EOETEAENESEESE: 


rest is a static posture, it has only one frame of 16 joint angles. cr is the abbreviation for “crawl”. It has 26 
frames of 8 (or 12, depending on the number of walking DOF) joint angles that form a repetitive gait. 
Expected body orientation defines the body angle when the robot is conducting the skill. If the body is tilted 
from the expected angles, the balancing algorithm will calculate some adjustments. Angle ratio is used 
when you want to store angles larger than the range of -128 to 127. Change the ratio to 2 so that you can 
save those large angles by dividing 2. 


(B) 


| SK posture has only one frame, and a gait has more than one frames and will be looped over. 
The following example is a behavior: 


1 const char pu[] PROGMEM = { //behavior 
DS Os il dln 


Se 2 
4 30, 30, O0, 0, 0, 0, 0, O, 60, 60, 70, 70, 15, 15, -70, -70, 
5 0, -40, O0, 0, 0, O0, O0, OO, 30, 30, 95, 95, 60, 60, -70, -70, 
6 5, 5, ©, 0, 0, O0, 0, 0, 75, 75, 55, 55, -50, -50, -75, -75, 
7 5, 5, ©, 0, 0, 0, 0, 0, 75, -70, 55, 55, -50, 70, -75, -75, 
8 60, -30, -45, 0, 0, O0, O0, O0, 70, -70, 55, O, -30, -45, -75, -45, 
Om: 


pu is short for “push up”, and is a “behavior”. Its data structure contains more information than posture and 
gait. 


The first four elements are defined the same as before, except that the number of frames is saved as a 
negative value to indicate that it's a behavior. The next three elements define the repeating frames in the 
sequence: starting frame, ending frame, looping cycles. So the 1, 2, 3 in the example means the behavior 
should loop from the second to the third frame three times (the index starts from zero). The whole behavior 
array will be executed only once, rather than looping over like the gait. 


Each frame contains 16 joint angles, and the last 4 elements define the speed of the transition, and the 
delay condition after each transition: 


1. The default speed factor is 4, it can be changed to an integer from 1 (slow) to 127 (fast). The unit is 
degree per step. If it's set to O, the servo will rotate to the target angle by its maximal speed (about 
0.07sec/60 degrees). It's not recommended to use a value larger than 10 unless you understand the 
risks. 


2. The default delay is 0. It can be set from O to 127, the unit is 50 ms. 


3. The 3rd number is the trigger axis. If it's not O, the previous delay time will be ignored. The trigger of the 
next frame will depend on the body angle on the corresponding axis. 1 for the pitch axis, and 2 for the 
roll axis. The sign of the number defines the direction of the threshold, i.e. if the current angle is smaller 
or larger than the trigger angle. 


4. The 4th number is the trigger angle. It can be -128 to 127 degrees. 


8.2.3. Suffix for indicating Instinct and Nevvbility 


You must upload WriteConst.ino to have the skills written to EEPROM for the first time. The following 
information will be used: 


1 const charx skillNameWithTypel] = 
Deer EN PU Nest WzZenoN be 
3 const char* progmemPointer[] = 


4 {er, pu, rest, zero, }; 


® Notice the suffix lor N in the skill name strings. They tell the program where to store skill data and 
when to assign their addresses. 


Later, if the uploaded sketch is the main sketch OpenCat.ino, and if you are using NyBoard that has an I2C 
EEPROM, the program will only need the pointer to the Newbility list 


const char* progmemPointer[] = {zero}; 


to extract the full knowledge of pre-defined skills. 


8.3. Define new skills and behaviors 


8.3.1 Modify the existing skill template 


There's already a skill called “zeroN” in InstinctNybble.h. It's a posture at the zero state waiting for your new 
definition. 


You can first use the command mIndex Offset to move an individual joint to your target position, then 


replace the joint angles (bold fonts) in array at once: 


1 const char zero[] PROGMEM = { 
201800 
SD Wh Oa Op Oy Oa Ca A Op Oy Op Oa A On Og Oo Oels 


Because it's declared as a Newbility and doesn't require writing to I2C EEPROM, you can simply upload 
OpenCat.ino every time you change the array (without uploading Writelnstinct.ino). You can trigger the 
new posture by pressing 7> on the IR remote, or type kzero in the serial monitor. 


You can rename this skill, but remember to update the keymap of the IR remote. 


8.3.2. Add more skills in InstinctNybble.h 


You can add more skills in InstinctNybble.h. Remember to increase the skill number at the beginning of the 
file and add the corresponding skill name and pointer in the skill list array. 


A skill can be called from the serial monitor with the token 'k' command. For example, ksit will move 
Nybble to posture “sit”. 


You can also tune new skills by sending posture frames through the serial port, using the m, i, tokens 
without uploading a new sketch. After fine-tuning the skill, you can save it in the instinctNybble.h and upload 
itto the board as a newbility or instinct. 


This git repo is a good starting point if you want to develop a customized gait. 


® Always check the actual code for the available skill names. We may alter the skill set as we iterate 
the software. 


8.3.3 Automation 
So far Nybble is controlled by the infrared remote. You make decisions for Nybble's behavior. 


You can connect Nybble with your computer or smartphone, and let them send out instructions 
automatically. Nybble will try its best to follow those instructions. 


By adding some sensors (like a touch sensor), or some communication modules (like a voice control 
module), you can bring new perception and decision abilities to Nybble. You can accumulate those 
automatic behaviors and eventually make Nybble live by itself! 


9 UU Understand OpenCat.h 


“Let the cat out of the bag.” Ie 


UIt will make another textbook. 


The controlling framework behind Nybble is OpenCat, which I've been developing for a while. You can read 
more stories from my posts on Hackster.io. 


OpenCat Framework 


Brain 
Al chip (Raspberry Pi) 


Perception 
Personality 
Random mood 
Decision 


Open choice of components 


Customizable parts 


Cerebellum and Spinal Cord 


Microcontroller (Arduino) 


Power management 
Instinctive movements 
Instructed movements 
Balancing 
Pre-crash and recovery 


Low level instructions 
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It's too much work for now [ls but you are welcome to discuss it with me on the forum or through email. 
Good thing is, | will keep the code compatible with future OpenCat models, and even your own DIY robots! 
Hopefully, the documentation will be completed during the processes. 


The Make of OpenCat 


10 U Mess Up with the Robot 


“Faster! Smarter! Cuter!” [] 


To be written by 0D YOU! 


Share your knowledge and creativity with the community at https://www.petoi.com/forum. 


Nybble Olympics 


* Speed: Faster 
e Skill: Smarter 


e Cuteness: Cuter 


nan CETTE 


Useful Links [ 


